SafeNet KSP for CNG registration utilities
CNG (Cryptography Next Generation) is Microsoft's cryptographic application programming interface (API), replacing the older Windows cryptoAPI (CAPI). CNG adds new algorithms along with additional flexibility and functionality. Thales provides SafeNet CSP for applications running in older Windows crypto environments (running CAPI), and SafeNet KSP for newer Windows clients (running CNG). Consult Microsoft documentation to determine which one is appropriate for your client operating system.
KSP must be installed on any computer that is intended to act via CNG as a client of the HSM, running crypto operations in hardware. You need KSP to integrate SafeNet Cryptoki with CNG and to use the newer functions and algorithms in Microsoft IIS.
After you register your HSM tokens with SafeNet KSP, your KSP code should work the same whether a SafeNet HSM (crypto provider) or the default provider is selected.
The SafeNet KSP utilities are installed in C:\Program Files\Safenet\ProtectToolkit 7\KSP. The installation includes the following utilities:
-
ksputil — Used to display and manage partition keys that are visible to the KSP
kspcmd
You can use this utility (C:\Program Files\Safenet\ProtectToolkit 7\CNG\kspcmd.exe) to register the KSP library and partitions via the Windows command line.
Note
To register the library and partitions using a GUI, use KspConfig. It is unnecessary to use both utilities.
Syntax
kspcmd.exe
library <path\cryptoki.dll>
password /s <token_label> [/u <username>] [/d <domain>]
usagelimit
viewslots
| Argument | Shortcut | Description |
|---|---|---|
| library <path\cryptoki.dll> | l | Register the library and associated provider names with KSP. |
| password | p | Register the designated token and its user PIN to the KSP. You can specify the following options:/s <token_label> — [Mandatory] The label of the token being registered to the KSP./u <username> — [Optional] The username to register for this partition. If this is not specified, all users on the client will be able to access this partition via KSP./d <domain> — [Optional] The domain to register for this token. |
| usagelimit | u | Set the maximum usage limit for RSA keys using KSP. Enter 0 to register unlimited uses. |
| viewslots | v | Display the registered slots by user/domain. |
Configuring the KSP using the command line
You can use the kspcmd command-line tool to configure the KSP for use with your tokens. The user must complete this procedure using Administrator privileges on the client.
You can register the following user/domain combinations with the KSP:
-
Administrator user with the domain specific to the client. Default Windows domains are in the format WIN-XXXXXXXXXXX.
-
SYSTEM user with the NT-AUTHORITY domain
The configuration tool registers a token PIN to a specific user, so that only that user can unlock the partition.
To configure the KSP using the command line
-
In a command line, navigate to the SafeNet KSP install directory and register the cryptoki.dll library to the KSP.
kspcmd library /s <path\cryptoki.dll> [/u <username>] [/d <domain>]
-
Register the designated token and its user PIN to the KSP.
kspcmd password /s <token_label> [/u <username>] [/d <domain>]
You are prompted to enter the user PIN for the token.
-
[Optional] Display the registered slots to ensure that registration is complete.
kspcmd viewslots
-
[Optional] Set the maximum usage limit for RSA keys using KSP.
kspcmd usagelimit
You are prompted to enter a usage limit. Enter 0 to register unlimited uses.
KspConfig
You can use this tool (C:\Program Files\Safenet\ProtectToolkit 7\CNG\KspConfig.exe) to register the KSP library and partitions using a GUI.
Note
To run KspConfig.exe, you must first install the Visual Studio 2015 redistributable package from Microsoft.
To register the library and partitions using the command line, use kspcmd. It is unnecessary to use both utilities.
Configuring the KSP using the GUI
You can use the KspConfig utility to configure the KSP for use with your tokens. The user must complete this procedure using Administrator privileges on the client.
You can register the following user/domain combinations with the KSP:
-
Administrator user with the domain specific to the client. Default Windows domains are in the format WIN-XXXXXXXXXXX.
-
SYSTEM user with the NT-AUTHORITY domain
The configuration tool registers a token PIN to a specific user, so that only that user can unlock the partition.
To configure the KSP using the GUI
-
In Windows Explorer, navigate to the SafeNet KSP install directory and launch KspConfig as the Administrator user.
-
In the left panel, double-click Register or View Security Library. Enter the filepath to cryptoki.dll or select Browse to locate it.
C:\Program Files\Safenet\ProtectToolkit 7\Runtime\lib\cryptoki.dll
Select Register to complete the registration.
-
In the left panel, double-click Register HSM Slots. Select the Administrator user, client domain, and an available token to register. Enter the user PIN and select Register Slot.
-
Select the SYSTEM user and NT-AUTHORITY domain and register for the token.
-
Repeat steps 3-4 for any other available tokens you want to register with the KSP.
You can now begin using your applications to perform crypto operations on the registered tokens.
ksputil
KSP binds machine keys to the host name of the crypto server that created the keys. You can use the ksputil utility to display and manage keys that are visible to the KSP.
Syntax
ksputil
clusterkeys /s <tokennum> /n <keyname> /t <target>
listkeys /s <tokennum> [/user]
| Argument | Shortcut | Description |
|---|---|---|
| clusterkeys | c | Bind a specified keypair to a different server domain. Note that this does not change the bindings of existing keys; it creates a copy of the original keypair that is bound to the new domain. Available options: /s <tokennum> — [Mandatory] The number of the token where the key(s) are located./n <keyname> — [Mandatory] The name of the key(s) to bind to the new domain./d <domain> — [Mandatory] The domain to which keys will be bound. |
| listkeys | l | Display a list of KSP-visible keys. Available options: /s <tokennum> — [Mandatory] The number of the token where the key(s) are located./user — [Optional] List keys bound to the currently logged-in user or host name. |
